Cloudinary の Named Transformation で画像変換 URL をシンプルにする
Guten Tag、ベルリンから伊藤です。
Cloudinary では、画像URLの変換パラメータを使って即座に変換を適用させることができます。
例えば、下記のように c_fill,w_200 部分で切り抜きオプション (c_fill) と幅のサイズ(w_200)を指定できますが、この切り抜きオプションを変更するだけで異なる変換を取得することができます。
https://res.cloudinary.com/CLOUD-NAME/image/upload/c_fill,w_200/ito-test/Reichstag.jpg
しかしながら、複雑に変換パラメータを組み合わせていくと URL が長くなってしまいます。今回紹介する Named Transformation （本記事では「名前付き変換」と呼びます）では、その名の通り変換を名前付けすることができます！
Named Transformation (名前付き変換) とは
例えば、c_fill,w_200 を "w_200_1"、c_crop,w_200 を "w_200_2" のように名前付き変換として保存すれば、冒頭の2つの画像はそれぞれ下記のように指定できるようになります。
https://res.cloudinary.com/CLOUD-NAME/image/upload/t_w_200_1/ito-test/Reichstag.jpghttps://res.cloudinary.com/CLOUD-NAME/image/upload/t_w_200_2/ito-test/Reichstag.jpg
この機能には、以下のようなメリットがあります。
- URL を短くさせられる
- 短く分かりやすい命名を使用し、変換を適用させる時のヒューマンエラーを避けやすい
- 適用している変換を隠すことができ、セキュリティ向上になる
◆ 英語ドキュメント: Named Transformations
設定方法
今回は、以下のような左の画像に対して右のロゴ画像をウォーターマークのように重ねるという変換を例に、名前付き変換を設定していきます。
コンソール
名前付き変換の作成
(1) まず [Transformations] 画面を開きます。
(2) 既存で変換がある場合はその変換の Edit を選択、新規で用意したい場合は右上の作成ボタンをクリックします。
(3) 必要に応じて変換を指定・変更し、[Save As] をクリックします。（※ 保存する変換パラメータには、f_auto、q_auto は含めてはいけません；注意点#1）
(4) ダイアログが出るので、保存する名前を指定し、[Save] します。
名前付き変換の確認
保存した名前付き変換は、Transformations のページのプルダウンで "Only named" を選択すると、一覧を確認することができます。
名前付き変換の適用
保存した名前の先頭に t_ を足して、普通の変換パラメータと同様に使うことができます。
また、画像の変換画面でも、More options をクリックし、Base transformation より名前付き変換を選択することができます。
名前付き変換の変更・削除
名前付き変換で指定している変換パラメータの内容を変更したい場合は、対象の変換の編集画面を開き、編集後、[Save] をクリックすると変更を保存できます。ここで保存した更新はすぐに適用されます。(※ 対象の名前付き変換を使う画像が1000件を超える場合には、既存の配信済みURLには更新内容が自動的に反映されません；注意点#2)
再び [Save As] をクリックすると、新しく保存（複製保存）となります。
削除するには、Transformations のページから Delete をクリックします。（※ 対象の名前付き変換を使う画像が1000件を超える場合、削除に失敗します；注意点#3）
API
Admin API を使って、名前付き変換の作成、確認、変更、削除ができます。ここでは、Pythonによる実行例を紹介します。
◆ 参考：PythonからCloudinaryを操作してみた ｜ Developers.IO
名前付き変換の作成
# パラメータ文字列による指定の場合
cloudinary.api.create_transformation("cm_logo",
"c_fit,h_400,w_600/c_scale,g_south_east,l_logo,o_70,w_100,x_10,y_10")
# パラメータ値による指定の場合
cloudinary.api.create_transformation("cm_logo",
dict(transformation=[
{'width' : 400, 'height' : 400, 'crop' : "fit" },
{'overlay' : "logo", 'gravity' : "south_east", 'crop' : "scale", 'width' : 100, 'opacity' :70, 'x' : 10, 'y' : 10}
]))
名前付き変換の確認
# 変換一覧の取得
a = cloudinary.api.transformations(
max_results = 2,
named = True )
print(json.dumps(a, indent=3))
# {
# "transformations": [
# {
# "name": "t_small_fill",
# "allowed_for_strict": true,
# "used": false,
# "named": true
# },
# {
# "name": "t_cm_logo",
# "allowed_for_strict": true,
# "used": false,
# "named": true
# }
# ],
# "next_cursor": "8707a4cbcf884204b103da47772ab9174e4f9b192cab6dbaec584fec4d87bb5c"
# }
# 特定の変換の取得
b = cloudinary.api.transformation(
transformation = "t_cm_logo")
print(json.dumps(b, indent=3))
# {
# "name": "t_cm_logo",
# "allowed_for_strict": true,
# "used": false,
# "named": true,
# "info": [
# {
# "height": 400,
# "width": 600,
# "crop": "fit"
# },
# {
# "gravity": "south_east",
# "overlay": "logo",
# "opacity": 70,
# "width": 100,
# "x": 10,
# "y": 10,
# "crop": "scale"
# }
# ],
# "derived": []
# }
next_cursor は、指定した最大取得件数 max_results より取得結果の数が多い場合に表示され、再度実行するときのオプションでこれを指定すると次の結果が得られます。
名前付き変換の適用
名前付き変換の名前を指定して、画像変換のURLを取得します。
cloudinary.CloudinaryImage("ito-test/Reichstag.jpg").image(
secure=True,
transformation=["cm_logo"])
# <img src="https://res.cloudinary.com/CLOUD-NAME/image/upload/t_cm_logo/ito-test/Reichstag.jpg"/>
名前付き変換の変更・削除
変換パラメータの内容を更新します。(※ 既存の配信済みURLには更新内容は自動的に反映されません；注意点#2)
cloudinary.api.update_transformation("cm_logo",
unsafe_update=dict(transformation=[
{"width" : 600, "height" : 600, "crop" : "fit" },
{"overlay" : "logo", "gravity" : "north_east", "crop" : "scale", "width" : 100, "opacity" :70, "x" : 10, "y" : 10}
]))
# {'message': 'updated'}
変換パラメータを削除します。（※ 対象の名前付き変換を使う画像が1000件以上ある場合、削除に失敗します；注意点#3）
cloudinary.api.delete_transformation("t_cm_logo")
# {'message': 'deleted'}
注意点
＃1 f_auto と q_auto は名前付き変換に含めてはいけない
画像やブラウザに合わせて webp など最適なフォーマットを提供する便利な変換パラメータ f_auto ですが、通常これを指定した場合、実際のフォーマットはCDNレベルで決定されるのだそうです。そのため、f_auto は名前付き変換の中に含めてはならず、CDNに見える状態にしなければなりません。
画像の重さと視覚的な品質で最適なバランスを提供する q_auto についても、同様です。(※)
そのため、これらを指定するには、名前付き変換の中で事前に定義するのではなく、下記のように組み合わせて使用します。
https://res.cloudinary.com/CLOUD-NAME/image/upload/t_w_200_1,f_auto,q_auto/ito-test/Reichstag.jpg
※ q_auto:[mode] (例: q_auto:good、q_auto:eco) の場合は名前付き変換に含めることが可能ですが、 Save-Data: on の Client Hint を使用するリクエストヘッダーに対して Cloudinary が適切に対応し、ecoに変換することができなくなるため、推奨されていません。Client Hint は Chrome や Opera などの一部のブラウザでサポートされている機能です。
◆ 英語ドキュメント: Can I use "f_auto" and "q_auto" inside my named-transformation?
＃2 （名前付き変換を使う画像が1000件を超える場合）更新は自動的に適用されない
コンソールで名前付き変換の内容を更新すると、更新した名前付き変換はすぐに反映され、それ以降に作成した新しい変換にだけでなく、既にアクセスしてキャッシュされた画像のURLにも次のアクセスで変更内容が適用されます。ただし、派生する画像が1000件以下の場合のみです。1000件を超える場合は、キャッシュクリアは自動的に行われません。
一方、API で更新を行った場合は、件数に関わらず、既にその変換を使っている配信中（変換が生成済み）のアセットに自動的に更新内容が反映されるわけではありませんでした。
APIで明示的にCDNキャッシュを削除する、あるいはバージョンや変換パラメータの順序を変える等で新しいURLパスを使うことにより、新たな変換を行わせると、更新した名前付き変換を使った画像を取得することができます。
▼ Python APIのCDNキャッシュ削除の実行例
cloudinary.uploader.explicit("ito-test/Reichstag", type = "upload",
eager = ["t_cm_logo"], invalidate = True)
◆ 英語ドキュメント: Upload API Reference - Explicit method
＃3 名前付き変換を使う画像が1000件を超える場合、削除に失敗する
コンソール/APIで名前付き変換を削除すると、その変換を使用する派生した変換画像も削除されます。しかし、派生する画像が1000件以上の場合、エラーとなります。この場合、別途、派生するリソースを削除する対処が必要となります。
なお、紐づく変換画像が削除されても、CDNのキャッシュは残るため、明示的にCDNキャッシュを削除しない限り、アクセス済みの変換画像URLはデフォルトの30日間表示し続けられます。
◆ 英語ドキュメント: How can I update a named transformation?
◆ 英語ドキュメント: How to delete derived resources?
以上、Cloudinary の Named Transformation、ぜひ活用してみてください！
クラスメソッドはCloudinaryのパートナーとして導入のお手伝いをさせていただいています。お気軽にこちらからお問い合わせください。こちらから無料でもサインアップいただけます。
